Versionning with GIT

Before starting...

Objectives

When you work with a computer, as a team or alone, you often need to save your progress, go back to a previous state of your work, allow for collaborators to contribute. This is what git is used for.

Using git is very simple, it does not require any complicated install or setup. This is why, even for a simple student labwork, handling your project directory with git is a good and lightweight idea.

This tutorial addresses the use of git in a specific way, which is very common. Understanding git from this specific usecase is a good entry point. Afterwards (not now...) you can imporove your knowledge by

• Visual Git Reference : nice explanations
• Visualizing Git Concepts with D3 : Interactive animations illustrating your git commands.
• Reading the docs: git homepage where a book is available online.

The usecase is the following:

1. I need a clever and safe disk space to work on a project. This disk space can be shared with others, actions on files can be undone, the successive stages of my work are versionned (i.e. I can go back to some previous state of the disk space), etc.
2. I create a "git repository" at a remote party where the clever and safe disk space associated to my project is available.
3. I mirror this disk space on a local disk, on my working machine. This is called "cloning" the remote git repository. The idea is to keep the two disk spaces synchronized: if I modify my local disk space, I have to make the remote one similar (we say "push" for this), and if somebody else has modified the remote disk space (by pushing), I have to bring these modifications to my local disk space (we say "pull" for this).
4. If several people have cloned my project repository, they may push modifications that could create conflicts with what I am currently doing on my local disk. If I push them, or if I pull, these conflicts are detected... and git provides a nice way to handle this. Sharing work on the same files is very convenient with git.

How is your repository organized

In your disk space for your project, on your machine, you will have a subdirectory named .git/. It is automatically handled by the git commands you will run. Do not remove this subdirectory, it would remove all your git features for your project disk space.

The main Git elements are :

• A file database. It is a directory (quite hidden to the user since it is within the .git directory) where all the versions of the files managed by git are stored. A specific version of some specific file that is stored is called a "blob" (Binary Large OBject). git does not manage "delta"s, i.e. it does not store an original file and then the successive modifications (i.e. deltas) that occurred to it. It stores a full copy of the first version of the file (one blob), a full copy of the second version (another blob corresponding to the same file), etc.

• A working directory. This is the directory of your project. Git puts here the appropriate version of the files that it manages when, for example, you ask it to retrieve some specific version of your project. This is what the user sees, so git modifies the files in the working directory when you ask it to see something else.

• A stage/index. Let us call it index. This contains the "current" version of all the files that git handles. This is not the working directory, since a file in the working directory may have been modified compared to the version that is stored in the index. The index can be viewed as the last snapshot of your project that git knows, under construction.

• The history of commits. Commits are snapshots of your project (one commit is very similar to what the index is). They are organized as a tree, as detailed further. This tree organization makes git able to organize the snapshots as an history of your project life, allowing several "stories" to be followed in parallel, as explained further.

The main element of git is a "commit". It can be viewed as a snapshot of your entire project. This snapshot is indeed the list of the blob references corresponding to the files (at the right version) that belong to the picture. The index (or staging area) can be viewed as the current snapshot, under construction. We can progressively add elements to the index and, at some point, create a commit from the index; git then registers the snapshot and assigns it a label.

The files in the working directory can have different status:

• untracked : No version of them is actually present in the index, i.e. git does not take care of them.

• tracked : Git knows about them, i.e. the index contains a version of the file. A tracked file can itself have one of the following status:

  • unmodified : the file in the working directory is the same as in the index

  • modified : the file in the working directory is different from the index

  • staged : modifications of the file have been added to the snapshot under construction

Note that a file can be both modified and staged if, at some points, we decided to store a version of the file in the index and the file was later modified without being again added to the index.

Getting started

Having an account

Ok, first you need to have an account at some places where a git server can provide you with remote disk space. There are some "free" ones, as github.com. CentraleSupélec students can use gitlab-student, which is sovereign.

Use a ssh key for interactions with the server

Using git makes a lot of interactions from your computer with the remote git server. Typing your login and password for each of them is exhausting. To avoid this, register a ssh key on your git account.

Ask for help for this stage ! Using git whithout having a ssh-key available is extremely annoying.

Create your repository

The web interface of your git server provides you with the possibility to create a project. Here, this is illustrated on CentraleSupélec gitlab-student.centralesupelec.fr server. Create an empty project, let us call this project "gabuzo" for this tutorial (choose the name you want for yours).

Then choose a project template... "Blank project" is enough for now.

Then you have to tell the project name (slug), set the visibility level (keep it private for now). You can toggle-out the "Initialize with a readme" box.

Then you are launched to your project page. Find the "url" of it. On gitlab, this is the "code" button. The url we need is the "clone with ssh" one.

For the gabuzo project on this illustration, the ssh-accessible url is git@gitlab-student.centralesupelec.fr:frezza/gabuzo.git... but, once again, replace this URL for the one you get.

This ssh-accessible url is denoted by <REMOTE_URL> in the following... so do not copy paste commands where <REMOTE_URL> appears, replace <REMOTE_URL> by something like git@gitlab-student.centralesupelec.fr:xxxx/gabuzo.git.

Clone your repository

Now, you are ready to have a disk space on your computer that is sychronized with the (empty for now) git repository you have just created.

First, the git command has to be available on your computer, make the required installations (sudo apt install git on Ubuntu, for example).

Then, at very first usage of git commands, you may be asked to define your name, e-mail... git suggests commands to do so, apply them first, and then retry.

Ok, let us clone. Go (cd <somewhere>) in a directory where you want your disk space to be created, and "clone" your project like this:

mylogin@mymachine:~$ git clone <REMOTE_URL>

It creates a gabuzo directory (or another one if you named your project differently). Let us go inside it.

mylogin@mymachine:~$ cd gabuzo

Let us check that it is actually a git directory:

mylogin@mymachine:~$ ls -al

You should see the .git subdirectory. Don't go into it, it is handled indirectly by the git commands you will type.

We can also check which is the remote repository we are synchronized with:

mylogin@mymachine:~$ git remote -v
origin  git@gitlab-student.centralesupelec.fr:xxxx/gabuzo.git (fetch)
origin  git@gitlab-student.centralesupelec.fr:xxxx/gabuzo.git (push)

Git can communicate with different servers, each communication channel is named, and can contain two directions: "fetch" to get data, "push" to send data. A channel is called a "remote", and here we have only one, named "origin". This is what you get by default when you clone a repository.

Start to work

Our first commits...

Edit (with a text file editor, as vscode... but not MSWord !) a Readme.md file, where you can write markdown code. You can add only a title line as # Welcome to the gabuzo project. Save the file (in the toplevel of your project directory... i.e. gabuzo/Readme.md).

This file is currently "untracked" (see section "How is your repository organized"). Git doesn't know it exists.

You can check this:

mylogin@mymachine:~$ git status
On branch main
Your branch is up to date with 'origin/main'.

...

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        Readme.md

It is not mandatory to check the status after each command but we will do that quite often here, for the sake of clarity.

Git considers that we have a current "snapshot" under construction, i.e. a kind of snapshot of your disk space that can be retrieved if needed. Let us add our Readme.md file to this under construction snapshot.

mylogin@mymachine:~$ git add Readme.md
mylogin@mymachine:~$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   Readme.md

The Readme.md file has passed from an "untracked" status to a "staged" status. It belongs to the current under construction snapshot. It is associated with a "blob".

For the moment, you have no traces of different configurations that your disk space has taken... indeed we are just starting from scratch. Let us check this (the --something flags are not mandatory but they clarify the output).

mylogin@mymachine:~$ git log --all --oneline --decorate --graph

Let us create our first history point, i.e. our first commit. It is nice to provide a message associated to the commit (i.e. a label, some conventions exist). It is a kind of comment, since commit identifiers are just a numerical code.

mylogin@mymachine:~$ git commit -am "ADD: Readme.md"

The -am meaning will be explained soon.

Retry the git log command, you will see that our history has registered a first "historical event", i.e. a first commit.

mylogin@mymachine:~$ git log --all --oneline --decorate --graph

This is what I got

* 0f357ca (HEAD -> main) ADD: Readme.md

Here, 0f357ca is the code, i.e. the unique identifier, of the commit. This is called "the SHA of the commit" (SHA = Secure Hash Algorithm). You recognize the comment we have added. Let us focus our attention on the (HEAD -> main) information... We will go back to this soon.

Nota: The real SHA (for this example) is 0f357ca7d2f669dda5aa8506218d0dabf124f44d, but you can provide only the beginning of it. For example

mylogin@mymachine:~$ git show 0f357ca

shows information about that commit. That command is super usefull to check the content of a commit, i.e. all the modifications that have been staged in that commit.

Let us represent this first commit like this (SHA are 0000, 0001, ... on the figure, not the SHA that you actually got).

Git handles several references to some commit.

The main one is a reference to the commit that is the "present time" of the history. It is the commit from which future modification will be made. This is called the HEAD. So we see here that our single commit 0f357ca is the HEAD.

Git can handle other references, among which the "branches" are very usefull. A branch is only a reference to some commit. By default, we have a branch called "main" (on some older git servers, called "master"). The output of git log says 0f357ca (HEAD -> main) because both the "main" branch and the HEAD refer to our single commit 0f357ca.

Let us see how many branches we have:

mylogin@mymachine:~$ git branch

You may see a single "main" branch, with a * in front of it. The * means that we are currently in that branch (useless here since we have only one branch... ok). We will see later what "being in a branch" actually means.

Ok, let us add some other lines in the Readme.md file (add some text, and save).

Once done, try :

mylogin@mymachine:~$ git status

Ignore the message about "origin/main" for now (our remote server is empty...), just be aware that git knows that our file is no more identical to the "blob" associated with the commit 0f357ca. The Readme.md file is now in the "modified" status.

In order to register the change, we have to create another commit. If we need to add a new file in this new commit, which is "untracked", a git add newfile would be required. Here, we want to add the new version of our file in the snapshot under construction. The git add Readme.md would do the job, making the new version of Readme.md be in the "staged" status. But usually, in the next snapshot, what you want is to add the new versions of all the currently tracked files, i.e. all the files in "unmodified", "modified" and "staged" state. This is what the a in -am does, the m meaning only "the next word in the command is the message".

The first time you want to track files, you have to add them explicitly. After that, only a git commit -am ... does the tracking. So for us:

mylogin@mymachine:~$ git commit -am "MODIF: Readme.md"
mylogin@mymachine:~$ git status

Except the error, we see that everyting is ok. Let us detail what has actually happened.

mylogin@mymachine:~$ git log --all --oneline --decorate --graph

I got

* 21c05bd (HEAD -> main) MODIF: Readme.md
* 0f357ca ADD: Readme.md

On top, we see our new commit, 21c05bd, just above the previous 0f357ca we already had. When we have added the new commit 21c05bd, git considers that it is a "child" of an existing one. Which one ? The current HEAD. So git created commit 21c05bd as a child of HEAD, i.e. a child of 0f357ca since HEAD had that value. After this, HEAD is now positionned to this new 21c05bd commit.

Before adding the new commit, HEAD was also similar to main. "Being in the main branch" actually means the HEAD and main both refer to the same commit. The branch "we are in" follows the shift of HEAD to the new commit.

Let us sum up:

• The history evolves from successive snapshots, named "commits".
• Evolution is made by adding a commit as the child of an existing one.
• That existing "parent" commit is one of the branches. That branch is the one equals to the head.
• When the commit is added, the concerned branch and the head shift to the new commit.

Branches and head may appear redundant. Indeed they are not. When you have several branches (not the case for us now), you can place the head to the one from which you want your history to progress. This is called "swiching to another branch". When you switch to another branch (or more generally to another commit), the content of your directory will be changed to match what was present at that commit. This is an important use case of GIT. Usually, we develop a new feature on a branch. It happens we need to fix code in the main branch. Git allows to switch the content of your working directory to that of the main branch, you fix the code, commit and push the change, and then can switch back to your feature branch.

You can also set the head to be a commit which is not a branch... in this case, the head is said "detached". We will not use that, but if you see errors related to "detached head", it means thot what you want to do requires the head to be positionned at one of the branches.

Save your work at server side

At server side, the disk space associated to your project is still empty. The git commands you have just performed on your computer are not automatically transmitted to the server.

We said that the local disk space and the remote one are synchronized. This is not really true, since they become the same only when you decide to make them similar.

Let us do it:

mylogin@mymachine:~$ git push

And that's it. try again

mylogin@mymachine:~$ git log --all --oneline --decorate --graph

There is a branch at server side, named origin/main that has been created (origin is the name of our "remote"). You can also see the files on the web interface of your project at server side.

Edit a new dummy.txt file, text file with few words in it, and save it. This can be done by

mylogin@mymachine:~$ echo "Hello, I am a dummy file !" > dummy.txt

It is "untracked". Let us track it :

mylogin@mymachine:~$ git add dummy.txt
mylogin@mymachine:~$ git status

It is "staged" now.

Let us modify Readme.md again, and save it. It becomes "modified", so it is not "staged" yet... but commit -am ... will make it "staged" before creating the commit, so no need to git add the modified file, as previoulsy explained.

mylogin@mymachine:~$ git status

Then, let us make a new commit

mylogin@mymachine:~$ git commit -am "ADD: dummy"

Now, try

mylogin@mymachine:~$ git log --all --oneline --decorate --graph

You will see that the HEAD and the local main branch have moved to this new commit, but origin/main is still associated to the previous commit. As far as we know at client side, this previous commit is the one associated to the main branch at server side.

To get server up to date with our modifications:

mylogin@mymachine:~$ git push
mylogin@mymachine:~$ git log --all --oneline --decorate --graph

Using what we have seen so far, you are ready to work alone, using git to save your work. You can retrieve past versions of your file, from past commit (we did not detail how for now, wait for the end of that tutorial). At least, do this simple git management for working safely.

Even if you work alone, having several branches is a good way to organize you work. This is addressed next. Branches are also very convenient for collaboration, as addressed at the end of this tutorial.

Using multiple branches

In many situations, the history of a project is not "linear", i.e. registering a succession of commits, organized as a chain, does not reflect how the work is done. The typical case is when you have something quite finalized but you want to refactor some part of it. Refactoring takes several steps, so the refactoring process needs to be saved into a succession of commits, not only one. During the production of these commits, the project, that was finalized, gets polluted by some "at work" files, since the refactoring takes time and need several saved "snapshots" before leading to the next finalized version : we would like to keep the clean almost finalized project available and perform the refactoring aside.

Having multiple branches solves this kind of issues. From the current finalized status of your project, i.e. the from commit where both HEAD and main branch are positionned, we create a new refactoring branch. It is a third variable (or the fourth if we take origin/main into account) storing the SHA of the current commit. Then, we ask git to make HEAD and refactoring follow next commits, and no more main, that will stay positionned to the current commit. Asking this is what we call "switching to the refactoring branch". Then we produce new commits for refactoring. Whille producing new commits, the HEAD and refactoring will progress in the commit tree. At the end, once refactoring is finished, we will conciliate the two "diverging" branches, a so called merge. We illustrate all these steps below.

Let us illustrate the use of branches with a fake project. Go at the toplevel of your project, and place the files hello_world.py and fake_printings.py there.

Let us track them, and make the 'finalized" commit.

mylogin@mymachine:~$ git add *.py
mylogin@mymachine:~$ git commit -am finalized
mylogin@mymachine:~$ git push
mylogin@mymachine:~$ git log --all --oneline --decorate --graph

As this fake project is supposed to be finalized, let us try the code (read the .py files, but do not modify them unless you are told).

mylogin@mymachine:~$ python hello_world.py 

Working on a new branch

Now let us create the new branch refactoring. As the log shows, it is only a new reference to our last commit (where HEAD is positionned to).

mylogin@mymachine:~$ git branch refactoring
mylogin@mymachine:~$ git log --all --oneline --decorate --graph

Note that the log displays HEAD -> main.

You can see which branches we now have

mylogin@mymachine:~$ git branch

mylogin@mymachine:~$ git switch refactoring
mylogin@mymachine:~$ git log --all --oneline --decorate --graph

mylogin@mymachine:~$ python hello_world.py 

mylogin@mymachine:~$ git commit -am "adding a frame"
mylogin@mymachine:~$ git log --all --oneline --decorate --graph

mylogin@mymachine:~$ git push

mylogin@mymachine:~$ git push --set-upstream origin refactoring

mylogin@mymachine:~$ git switch main

mylogin@mymachine:~$ git commit -am "BUGFIX: 2 line breaks"
mylogin@mymachine:~$ git push
mylogin@mymachine:~$ git log --all --oneline --decorate --graph

mylogin@mymachine:~$ git switch refactoring

mylogin@mymachine:~$ python hello_world.py 

mylogin@mymachine:~$ git commit -am "BUGFIX: frame adjusted"
mylogin@mymachine:~$ git push
mylogin@mymachine:~$ git log --all --oneline --decorate --graph

mylogin@mymachine:~$ git switch main
mylogin@mymachine:~$ git log --all --oneline --decorate --graph

mylogin@mymachine:~$ git merge refactoring
mylogin@mymachine:~$ git log --all --oneline --decorate --graph

mylogin@mymachine:~$ git push

mylogin@mymachine:~$ git switch main

mylogin@mymachine:~$ git commit -am "MODIF: French"
mylogin@mymachine:~$ git push
mylogin@mymachine:~$ git log --all --oneline --decorate --graph

mylogin@mymachine:~$ git switch refactoring

mylogin@mymachine:~$ git commit -am "MODIF: German"
mylogin@mymachine:~$ git push
mylogin@mymachine:~$ git log --all --oneline --decorate --graph

mylogin@mymachine:~$ git switch main

mylogin@mymachine:~$ git switch merge refactoring

mylogin@mymachine:~$ git log --all --oneline --decorate --graph

mylogin@mymachine:~$ git commit -am "French chosen"
mylogin@mymachine:~$ git push
mylogin@mymachine:~$ git log --all --oneline --decorate --graph

mylogin@mymachine:~$ git commit -am "..."
mylogin@mymachine:~$ git pull

mylogin@mymachine:~$ git switch main
mylogin@mymachine:~$ rm hello_world.py
mylogin@mymachine:~$ echo "I am a new file" > nice-file.txt
mylogin@mymachine:~$ git add nice-file.txt
mylogin@mymachine:~$ git commit -am "Adding nice file"
mylogin@mymachine:~$ git push

mylogin@mymachine:~$ echo "Ok... write what you want" > another-file.txt
mylogin@mymachine:~$ git add another-file.txt
mylogin@mymachine:~$ git commit -am "Another file added"
mylogin@mymachine:~$ git push

mylogin@mymachine:~$ git log --max-count=1 --diff-filter=D -- hello_world.py

mylogin@mymachine:~$ git rev-parse 1234567890^

mylogin@mymachine:~$ git rev-parse 1234^

mylogin@mymachine:~$ git restore --source=09876 -- hello_world.py
mylogin@mymachine:~$ git add hello_world.py
mylogin@mymachine:~$ git commit -am "Restoring hello_world.py"
mylogin@mymachine:~$ git push

mylogin@mymachine:~$ mkdir MyEmptyDir
mylogin@mymachine:~$ touch MyEmptyDir/.gitkeep
mylogin@mymachine:~$ git add MyEmptyDir/.gitkeep
mylogin@mymachine:~$ git commit -am "ADD: MyEmptyDir"
mylogin@mymachine:~$ git push

*.aux
*.bbl
*.blg
*.ilg
*.out
*.toc
*.ind
*.flg 
*.fls
*.glo
*.log
*.idx
*.maf 
*.mtc*
*eps-converted-to*
*fdb_latexmk